home *** CD-ROM | disk | FTP | other *** search
/ Nebula 1 / Nebula One.iso / Internet / WWW / Perl_WWW_Utilities / weblog1.1 / uncgi / README < prev    next >
Encoding:
Text File  |  1995-06-25  |  7.5 KB  |  210 lines
  1.  
  2.                              UN-CGI VERSION 1.2
  3.                                        
  4. Contents
  5.  
  6.      * Introduction
  7.      * Installation
  8.      * Usage
  9.      * Other Features
  10.      * Bugs
  11.      * Frequently Asked Questions
  12.        
  13. Introduction
  14.  
  15.    
  16.    
  17.    This is uncgi 1.1, a frontend for processing queries and forms from
  18.    the Web on UNIX systems. You can get it via anonymous ftp from
  19.    ftp.hyperion.com or, depending on your browser, by following this
  20.    link.
  21.    
  22.    Without this program, if you wanted to process a form, you'd have to
  23.    either write or dig up routines to translate the values of the form's
  24.    fields from "URL encoding" to whatever your program required. This was
  25.    a hassle in C, and a real pain in the shell, and you had do things
  26.    differently for GET and POST queries.
  27.    
  28.    Which is where uncgi comes in. It decodes all the form fields and
  29.    sticks them into environment variables for easy perusal by a shell
  30.    script, a C program, a Perl script, or whatever you like, then
  31.    executes whatever other program you specify.
  32.    
  33.    (Actually, "uncgi" is something of a misnomer, as the weird URL syntax
  34.    is from the HTML forms specification, not from CGI itself.)
  35.    
  36. Installation
  37.  
  38.    
  39.    
  40.    To install, edit the Makefile, setting "CGI_BIN" to point to your HTTP
  41.    server's CGI directory. Under NCSA httpd, this is usually a directory
  42.    called "cgi-bin" in the server root directory. Then run "make
  43.    install".
  44.    
  45.    Note that the variable serves two purposes as supplied: it tells the
  46.    Makefile where to install uncgi, and it also tells uncgi where to look
  47.    for backend scripts. If you would like uncgi to look in a directory
  48.    other than the one it's installed in, set DESTDIR to the install
  49.    directory and CGI_BIN to the directory containing the scripts and
  50.    programs that uncgi will be executing.
  51.    
  52. Usage
  53.  
  54.    
  55.    
  56.    An example is the easiest way to demonstrate uncgi's use. Suppose you
  57.    have the following in an HTML file:
  58.  
  59. <form method=POST action="/cgi-bin/uncgi/myscript/thanks.html">
  60. What's your name?
  61. <input type=text size=30 name=name>
  62. <p>
  63. Type some comments.
  64. <br>
  65. <textarea name=comments rows=10 cols=60></textarea>
  66. What problem are you having? <select name=problem multiple>
  67. <option> Can't sleep
  68. <option> Unruly goat
  69. <option> Limousine overcrowding
  70. </select>
  71. <p>
  72. <input type=submit value="  Send 'em in!  ">
  73. </form>
  74.  
  75.    When the user selects the "Send 'em in!" button, the HTTP server will
  76.    run uncgi. Uncgi will set three environment variables, WWW_name,
  77.    WWW_comments and WWW_problem, to the values of the "name", "comments",
  78.    and "problem" fields in the form, respectively. Then it will execute
  79.    myscript in the CGI_BIN directory. If more than one "problem" is
  80.    selected, the values will all be placed in WWW_comments, separated by
  81.    hash marks ('#').
  82.    
  83.    All the usual CGI environment variables (PATH_INFO, QUERY_STRING,
  84.    etc.) are available to the script or program you tell uncgi to run. A
  85.    couple of them (PATH_INFO and PATH_TRANSLATED) are tweaked by uncgi to
  86.    the values they'd have if your program were being executed directly by
  87.    the server. In the above example, when uncgi ran myscript, PATH_INFO
  88.    would be set to "/thanks.html". This is an easy way to specify
  89.    additional parameters to your script without resorting to hidden
  90.    fields.
  91.    
  92.    Myscript might be as simple as this:
  93.  
  94. #!/bin/sh
  95. echo 'Content-type: text/html'
  96. echo ''
  97. mail webmaster << __EOF__
  98. $WWW_name said:
  99. $WWW_comments
  100. __EOF__
  101. cat $PATH_TRANSLATED
  102.  
  103.    With uncgi, that's all you need to do to write a script to send you
  104.    mail from a form and print a prewritten file as a response. And it's
  105.    the same whether you want to use GET or POST queries.
  106.    
  107. Other Features
  108.  
  109.    
  110.    
  111.    Extra feature: If you compile with -DNO_MAIN, you can use uncgi as a
  112.    library function in a C program of your own. Just call uncgi() at the
  113.    start of your program.
  114.    
  115.    Uncgi will handle hybrid GET/POST requests. Specify a method of POST
  116.    in the form, and add a GET-style query string to the action, for
  117.    example <form method=POST
  118.    action="/cgi-bin/uncgi/myscript?form_id=feedback">. When your script
  119.    is run, WWW_form_id will be set to "feedback". This will only work if
  120.    your HTTP server supports it (NCSA's does, for now anyway.)
  121.    
  122. Bugs
  123.  
  124.    
  125.    
  126.    There should be a way to specify a list of directories that uncgi will
  127.    search for backend scripts.
  128.    
  129. Frequently Asked Questions
  130.  
  131.   WHERE DO I PUT EVERYTHING?
  132.   
  133.    
  134.    
  135.    Short answer: Your server's cgi-bin directory.
  136.    
  137.    Long answer: When you edit uncgi's Makefile, you'll see two macro
  138.    definitions. The first, CGI_BIN, tells uncgi where to look for your
  139.    scripts or programs. It must be set to the name of an existing
  140.    directory; you can set it to any directory you like. Usually it's set
  141.    to the location of your server's cgi-bin directory.
  142.    
  143.    The second, DESTDIR, tells the Makefile where to install uncgi. By
  144.    default, it's set to the same thing CGI_BIN is. It must point to your
  145.    server's cgi-bin directory, so you'll need to change it if you set
  146.    CGI_BIN to something else.
  147.    
  148.   WHY DOES UNCGI TELL ME IT CAN'T RUN MY SCRIPT?
  149.   
  150.    
  151.    
  152.    First, make sure your script is in the right place; see the preceding
  153.    section.
  154.    
  155.    Second, make sure your script can be executed by the server. Remember,
  156.    the server probably isn't running from your account, so you need to
  157.    set the permissions on your script such that it can be run by any
  158.    user. Usually, you can say "chmod 755 scriptname" (replacing
  159.    scriptname with the name of your script) to set the permissions
  160.    properly.
  161.    
  162.   WHAT DO I DO IN MY FORMS?
  163.   
  164.    
  165.    
  166.    The <form> tag has two attributes, METHOD and ACTION. METHOD must be
  167.    set to either GET or POST; uncgi will handle either one, but POST is
  168.    preferred if you have textarea fields or are expecting a lot of
  169.    information from the client. Note that the attribute name (METHOD) can
  170.    be upper or lower case, but the value must be all caps.
  171.    
  172.    ACTION should have the following components:
  173.      * The alias for your server's cgi-bin directory (usually just
  174.        /cgi-bin/)
  175.      * uncgi/ to tell the server which program to execute.
  176.      * The name of your script as it appears in the directory where you
  177.        told uncgi to find your scripts and programs (the CGI_BIN macro in
  178.        the Makefile.) Example: myscript
  179.      * Optionally, a forward slash followed by additional parameters,
  180.        often the path to another file you want your script to print. This
  181.        path information will be available to your script in the PATH_INFO
  182.        and PATH_TRANSLATED environment variables (the latter contains the
  183.        full path to the document, including the path to the server root
  184.        directory.) Note that you can't use tilde notation. Example:
  185.        /form_output/acknowledge.html
  186.        
  187.    
  188.    
  189.    So, if you wanted to tell uncgi to run sendmemail with no additional
  190.    parameters, you'd put sendmemail in the directory you specified as the
  191.    value of CGI_BIN in uncgi's makefile, and use the following tag to
  192.    begin your form:
  193.    
  194.      <form method=POST action="/cgi-bin/uncgi/sendmemail">
  195.      
  196.   I GET AN ERROR CODE 500 FROM THE SERVER.
  197.   
  198.    
  199.    
  200.    This usually means your script isn't specifying a content type to the
  201.    server. The first thing your script needs to output is:
  202.    
  203.      Content-type: text/html
  204.      
  205.    followed by a blank line.
  206.      _________________________________________________________________
  207.    
  208.       Maintained by Steven Grimm <koreth@hyperion.com>.
  209.       Send mail if you have comments or suggestions.
  210.